epigraph.dev

Epigraph Web Components

Web Components that provide encapsulated functions and scoped styles. The attributes sku and ua-code are required for all web components and render modes.Note that some class names and values used in the snippets are arbitrary and meant to be replaced by the developer. For example, some-valid-sku or some-valid-ua-code are meant to be replaced.

<epigraph-ar>

Epigraph’s custom web component for AR based on Google’s <model-viewer>. As such, it mostly follows their coding conventions except for public APIs. For more information, see Google Model-Viewer Code Conventions

Quick Start

To get started with the latest stable version, simply place one of the following scripts in the <head>, pick one of the display modes you wish to use, and then use the example snippet as template to insert an instance of this web component.

Import Snippet

<!-- include this in your `<head>` -->
<script
  async
  type="module"
  src="https://cdn.jsdelivr.net/npm/@epigraph/ar/dist/epigraph-ar.min.js"
></script>

Specific Version Import Snippet

<!-- include this in your `<head>`, replace version-number with a specified version -->
<script
  async
  type="module"
  src="https://cdn.jsdelivr.net/npm/@epigraph/[email protected]/dist/epigraph-ar.min.js"
></script>

Render Modes

Described in this section are all the visual modes that this web component can be rendered in.

Expand Section

3D Viewer and AR/QR Button

<epigraph-ar
  viewer-visible
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
></epigraph-ar>

related example

AR/QR Button Only

Default
<epigraph-ar
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
></epigraph-ar>

related example

Use Custom Button
<epigraph-ar sku="some-valid-sku" ua-code="some-valid-ua-code">
  <button class="some-custom-button" slot="ar-button"></button>
</epigraph-ar>

related example

3D Viewer Only

<epigraph-ar
  viewer-visible
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
  button-mode="none"
></epigraph-ar>

related example

Using 3D Viewer and AR Button Separately

<div class="epigraph-ar-container" style="any style you need to specify">
  <epigraph-ar
    viewer-visible
    sku="some-valid-sku"
    ua-code="some-valid-ua-code"
    button-mode="none"
  ></epigraph-ar>
</div>

<div
  class="epigraph-ar-button-container"
  style="any style you need to specify"
>
  <epigraph-ar
    sku="some-valid-sku"
    ua-code="some-valid-ua-code"
  ></epigraph-ar>
</div>

related example

3D viewer with material variant selector (WIP)

<!-- NOTE: only supported on Android Devices compatible with WebXR -->
<epigraph-ar
  viewer-visible
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
  ar-modes="webxr"
  button-mode="none"
  material-variant-selector-visible
></epigraph-ar>

3D viewer with material variant selector and AR (WIP)

<!-- NOTE: only supported on Android Devices compatible with WebXR -->
<epigraph-ar
  viewer-visible
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
  ar-modes="webxr"
  material-variant-selector-visible
></epigraph-ar>

Product Tour Only

<epigraph-ar
  viewer-visible
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
  button-mode="none"
  product-tour-visible
></epigraph-ar>

related example

Full Product Tour

<epigraph-ar
  viewer-visible
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
  product-tour-visible
></epigraph-ar>

related example

Full Product Tour with Button Outside

<div class="epigraph-ar-container" style="any style you need to specify">
  <epigraph-ar
    viewer-visible
    product-tour-visible
    sku="some-valid-sku"
    ua-code="some-valid-ua-code"
    button-mode="none"
  ></epigraph-ar>
</div>

<div
  class="epigraph-ar-button-container"
  style="any style you need to specify"
>
  <epigraph-ar
    sku="some-valid-sku"
    ua-code="some-valid-ua-code"
  ></epigraph-ar>
</div>

related example

Visual API

API available for you to modify the experiences rendered.

Expand Section

AR/QR Button

Attributes and Properties
Property Attribute Modifiers Type Default Description
arButtonModeAttribute button-mode   string “mobile desktop” sets ar button modes for the ar-button, maps to the enumeration

none - NONE

mobile - MOBILE

desktop - DESKTOP

mobile desktop - BOTH
arButtonRolloverNudge ar-button-rollover-nudge   boolean false toggles the ability to show a rollover nudge on hover if used in button only mode
CSS Custom Properties
Property Description
--ar-button-active-background-color edits ar-button background color when clicked
--ar-button-background-color edits ar-button background color
--ar-button-border-color edits ar-button border color
--ar-button-hover-background-color edits ar-button background color when hovered
--ar-button-hover-text-color edits ar-button text color when hovered
--ar-button-text-color edits ar-button text color
--ar-icon-frame-color edits ar-icon frame color
--ar-icon-hover-frame-color edits ar-icon frame color when hovered
--ar-icon-hover-vector-1-color edits ar-icon vector 1 (top face) color when hovered
--ar-icon-hover-vector-2-color edits ar-icon vector 2 (left face) color when hovered
--ar-icon-hover-vector-3-color edits ar-icon vector 3 (right face) color when hovered
--ar-icon-vector-1-color edits ar-icon vector 1 (top face) color
--ar-icon-vector-2-color edits ar-icon vector 2 (left face) color
--ar-icon-vector-3-color edits ar-icon vector 3 (right face) color
CSS Shadow Parts
Part Description
ar-button-container points to the ar button container
default-ar-button points to the default ar button
ar-button-rollover-nudge points to the rollover nudge
Slots
Name Description
ar-button replaces the ar-button but maintains the onclick function
ar-button-rollover-nudge replaces the nudge section that appears on hover
Theming

It is possible to create a theme by combining CSS Shadow Parts and CSS Custom Properties.

Naming Conventions

For consistency’s sake, please name your client custom properties like this

--{client}_{color-name} or --{client}_{property-name}

Selectors

You can target the web component directly using its tag name epigraph-ar

Format

Organization here is optional but is recommended best practice.

You can theme the button by replacing the default HTML

<epigraph-ar>
  <button slot="ar-button"></button>
</epigraph-ar>

and/or by some specific styling

epigraph-ar {
  /* define client colors and properties first here
        keep in mind that the following names
        and values are arbitrary */
  --client_theme-color: #5d5fef;
  --client_color-dark: #1f1f1f;
  --client_color-default: #404040;
  --client_color-light: #ffffff;
  --client_loading-radius: 3rem;
  --client_loading-thickness: 0.625rem;
  /* ... more specific colors if you want */

  /* ar button theming */
  --ar-button-active-background-color: var(
    defined property for the desired color
  );
  --ar-button-background-color: var(
    defined property for the desired color
  );
  --ar-button-border-color: var(defined property for the desired color);
  --ar-button-hover-background-color: var(
    defined property for the desired color
  );
  --ar-button-hover-text-color: var(
    defined property for the desired color
  );
  --ar-button-text-color: var(defined property for the desired color);

  /* ar icon theming */
  --ar-icon-frame-color: var(defined property for the desired color);
  --ar-icon-hover-frame-color: var(defined property for the desired color);
  --ar-icon-hover-vector-1-color: var(
    defined property for the desired color
  );
  --ar-icon-hover-vector-2-color: var(
    defined property for the desired color
  );
  --ar-icon-hover-vector-3-color: var(
    defined property for the desired color
  );
  --ar-icon-vector-1-color: var(defined property for the desired color);
  --ar-icon-vector-2-color: var(defined property for the desired color);
  --ar-icon-vector-3-color: var(defined property for the desired color);
}

epigraph-ar::part(ar-button-container) {
  /* desired styles here for the internal button container */
}

epigraph-ar::part(default-ar-button) {
  /* desired styles here for the default ar-button */
}

3D Viewer

Attributes and Properties
Property Attribute Modifiers Type Default Description
arModes ar-modes   string “scene-viewer quick-look” sets ar modes for the ar experience

webxr/scene-viewer - android

quick-look - iOS
arPlacement ar-placement   string “floor” sets ar placement for the ar experience

floor - place ar object on the floor

wall - place ar object on the wall
autoStart auto-start   boolean false used to load the 3D viewer automatically on desktop
cameraOrbit camera-orbit   string “55deg 69deg auto” sets the viewer camera orbit values
canActivateAR   readonly     public method to get ar-capability status
environmentImage environment-image   string “neutral” sets environmental lighting

empty string - default scene optimized for load speed

neutral - applies even lighting on all sides

HDR Image - supply HDR Image source url to this to apply custom lighting
interactionPromptThreshold interaction-prompt-threshold   number 3000 modifies amount of idling time before interaction prompt appears
internalMeasurementsVisible internal-measurements-visible   boolean false sets visibility of internal model measurements
maxCameraOrbit max-camera-orbit   string “auto 100deg auto” sets the maximum camera orbit

each part of the string represents the following in order: roll(theta) yaw(phi) radius

this uses Euler angles @see https://en.wikipedia.org/wiki/Euler_angles#Proper_Euler_angles_2 for more information
measurementUnit measurement-unit   string “imperial” sets which measurement system to use for internal measurements

imperial - uses the imperial system

metric - uses the metric system
minCameraOrbit min-camera-orbit   string “auto 0deg auto” sets the minimum camera orbit

each part of the string represents the following in order: roll(theta) yaw(phi) radius

this uses Euler angles @see https://en.wikipedia.org/wiki/Euler_angles#Proper_Euler_angles_2 for more information
orbitSensitivity orbit-sensitivity   number 1 sets the orbit sensitivity

takes any number, negative values reverse orbit
shadowIntensity shadow-intensity   number 1 modifies the shadow intensity of the model
showPosterOnClose show-poster-on-close   boolean false sets ability to reset model-viewer to poster upon closing fullscreen
sku sku   string, required ”” to be used with epigraph product skus
stopTouchPropagation stop-touch-propagation   boolean false modifies whether touch events on the 3D viewer are allowed to propagate
theme theme   string “default” used to indicate UI/UX themes
viewerVisible viewer-visible   boolean false sets visibility of the 3D viewer
disableMobileFullscreen disable-mobile-fullscreen   boolean false used to disable fullscreen on mobile devices
viewerMaximizable viewer-maximizable   boolean false toggles the ability to maximize the 3D viewer on mobile
posterBackground poster   string ”” sets the source url for the poster background
posterForeground poster-foreground   string ”” sets the source url for the icon to display on top of the poster
CSS Custom Properties
Property Description
--progress-ring-color edits the progress ring color
--progress-ring-radius edits the progress ring radius
--progress-ring-thickness edits the progress ring thickness
CSS Shadow Parts
Part Description
default-poster-background points to the default poster background
default-poster-foreground points to the default poster icon
model-viewer points to the <model-viewer> element
poster-foreground points to the poster icon
viewer-modal-exit-button points to the default viewer modal exit button
webxr-banner points to the webxr banner
webxr-banner-text points to the text portion of the webxr banner
webxr-banner-name points to the product name in the text portion
webxr-banner-pdp points to the the url text below the name in the text portion
webxr-banner-visit-button points to the visit button in the banner
Events
Event Type Description
epigraph-ar-capability-determined CustomEvent<{ canActivateAr: any; }> custom event to indicate whether the device is AR capable
epigraph-ar-loading-error CustomEvent<{ message: any; stack: any; }> custom event to bubble up the model load error event from model-viewer, inheriting message and stack
epigraph-ar-model-loaded   custom event to bubble up the model loaded event from model-viewer
Methods
Method Type Description
dismissPoster (): void public method to dismiss viewer poster
showPoster (): void public method to show viewer poster
closeModal (): void public method to close iOS fullscreen modal
launchFullscreen (): void public method to open fullscreen or fullscreen modal
Slots
Name Description
poster replaces the viewer poster
progress-bar replaces the progress indicator
viewer-modal-exit-button replaces the viewer modal exit button
Theming

It is possible to create a theme by combining CSS Shadow Parts and CSS Custom Properties.

Naming Conventions

For consistency’s sake, please name your client custom properties like this

--{client}_{color-name} or --{client}_{property-name}

Selectors

You can target the web component directly using its tag name epigraph-ar

Format

Organization here is optional but is recommended best practice.

You can theme the viewer by replacing some component’s HTML

<epigraph-ar>
  <div slot="progress-bar"></div>
  <div slot="poster"></div>
</epigraph-ar>

and/or by some specific styling

epigraph-ar {
  /* define client colors and properties first here
        keep in mind that the following names
        and values are arbitrary */
  --client_theme-color: #5d5fef;
  --client_color-dark: #1f1f1f;
  --client_color-default: #404040;
  --client_color-light: #ffffff;
  --client_loading-radius: 3rem;
  --client_loading-thickness: 0.625rem;
  /* ... more specific colors if you want */

  /* progress ring theming */
  --progress-ring-color: var(defined property for the desired color);
  --progress-ring-radius: var(defined property for the desired value);
  --progress-ring-thickness: var(defined property for the desired value);
}

QR Modal

CSS Custom Properties
Property Description
--qr-modal-close-button-stroke-color edits qr-modal close button stroke color
--qr-modal-done-button-active-background-color edits qr-modal done button background color when clicked
--qr-modal-done-button-background-color edits qr-modal done button background color
--qr-modal-done-button-border-color edits qr-modal done button border color
--qr-modal-done-button-hover-background-color edits qr-modal done button background color when hovered
--qr-modal-done-button-hover-text-color edits qr-modal done button text color when hovered
--qr-modal-done-button-text-color edits qr-modal done button text color
--qr-modal-instruction-color edits qr-modal instruction text color
--qr-modal-r--qr-modal-requirement-color edits qr-modal requirement text color
--qr-modal-title-color edits qr-modal title text color
CSS Shadow Parts
Part Description
qr-modal points to the <qr-modal> element
qr-modal-background points to the modal background
qr-modal-close-default points to the default close button in the qr-modal
qr-modal-container points to the main modal
qr-modal-done-default points to the default done button in the qr-modal
qr-modal-instruction-default points to the default instruction in the qr-modal
qr-modal-qr-container points to the qr container within the qr-modal
qr-modal-qr-image points to the qr image in the modal
qr-modal-requirement-default points to the default requirement in the qr-modal
qr-modal-title-default points to the default title in the qr-modal
Slots
Name Description
qr-modal-close replaces the qr-modal close button
qr-modal-done replaces the qr-modal done button
qr-modal-instruction replaces the qr-modal instruction
qr-modal-requirement replaces the qr-modal requirement
qr-modal-title replaces the qr-modal title
Theming

It is possible to create a theme by combining CSS Shadow Parts and CSS Custom Properties.

Naming Conventions

For consistency’s sake, please name your client custom properties like this

--{client}_{color-name} or --{client}_{property-name}

Selectors

You can target the web component directly using its tag name epigraph-ar

Format

Organization here is optional but is recommended best practice.

You can theme the button by replacing the default HTML

<epigraph-ar>
  <div slot="qr-modal-close"></div>
  <div slot="qr-modal-done"></div>
  <div slot="qr-modal-instruction"></div>
  <div slot="qr-modal-requirement"></div>
  <div slot="qr-modal-title"></div>
</epigraph-ar>

and/or by some specific styling

epigraph-ar {
  /* define client colors and properties first here
        keep in mind that the following names
        and values are arbitrary */
  --client_theme-color: #5d5fef;
  --client_color-dark: #1f1f1f;
  --client_color-default: #404040;
  --client_color-light: #ffffff;
  --client_loading-radius: 3rem;
  --client_loading-thickness: 0.625rem;
  /* ... more specific colors if you want */

  /* qr modal theming */
  --qr-modal-close-button-stroke-color: var(
    defined property for the desired color
  );
  --qr-modal-done-button-active-background-color: var(
    defined property for the desired color
  );
  --qr-modal-done-button-background-color: var(
    defined property for the desired color
  );
  --qr-modal-done-button-border-color: var(
    defined property for the desired color
  );
  --qr-modal-done-button-hover-background-color: var(
    defined property for the desired color
  );
  --qr-modal-done-button-hover-text-color: var(
    defined property for the desired color
  );
  --qr-modal-done-button-text-color: var(
    defined property for the desired color
  );
  --qr-modal-instruction-color: var(
    defined property for the desired color
  );
  --qr-modal-requirement-color: var(
    defined property for the desired color
  );
  --qr-modal-title-color: var(defined property for the desired color);
}

epigraph-ar::part(qr-modal) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-background) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-close-default) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-container) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-done-default) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-instruction-default) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-qr-container) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-qr-image) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-requirement-default) {
  /* desired styles here */
}

epigraph-ar::part(qr-modal-title-default) {
  /* desired styles here */
}

Material Variant Selector

Attributes and Properties
Property Attribute Modifiers Type Default Description
materialVariantSelectorVisible material-variant-selector-visible   boolean false sets visibility of material variant selector
CSS Shadow Parts
Part Description
material-variant-selector points to the <material-variant-selector> element
material-variant-selector-button points to the selector buttons themselves
material-variant-selector-container points to the container housing the selectors
Theming

It is possible to create a theme by combining CSS Shadow Parts and CSS Custom Properties.

Naming Conventions

For consistency’s sake, please name your client custom properties like this

--{client}_{color-name} or --{client}_{property-name}

Selectors

You can target the web component directly using its tag name epigraph-ar

Format

Organization here is optional but is recommended best practice.

You can theme the button by replacing the default HTML

and/or by some specific styling

epigraph-ar {
  /* define client colors and properties first here
        keep in mind that the following names
        and values are arbitrary */
  --client_theme-color: #5d5fef;
  --client_color-dark: #1f1f1f;
  --client_color-default: #404040;
  --client_color-light: #ffffff;
  --client_loading-radius: 3rem;
  --client_loading-thickness: 0.625rem;
  /* ... more specific colors if you want */
}

epigraph-ar::part(material-variant-selector) {
  /* desired styles here */
}
epigraph-ar::part(material-variant-selector-button) {
  /* desired styles here */
}
epigraph-ar::part(material-variant-selector-container) {
  /* desired styles here */
}

Product Tour

Attributes and Properties
Property Attribute Modifiers Type Default Description
productTourVisible product-tour-visible   boolean false sets visibility of product tour
CSS Custom Properties
Property Description
--hotspot-button-background-color edits hotspot button background color
--hotspot-button-border-color edits hotspot button border color
--hotspot-button-focus-border-color edits hotspot button border color when focused
--hotspot-inner-circle-border-color edits hotspot button inner circle border color
--hotspot-inner-circle-viewed-border-color edits hotspot button inner circle border color when viewed
--mobile-product-tour-button-background-color edits product-tour mobile button background color
--mobile-product-tour-button-text-color edits product-tour mobile button text color
--product-tour-background-color edits product-tour background color
--product-tour-close-button-fill-color edits product-tour close button fill color
--product-tour-close-button-hover-fill-color edits product-tour close button fill color when hovered
--product-tour-close-button-hover-stroke-color edits product-tour close-button stroke color when hovered
--product-tour-close-button-stroke-color edits product-tour close-button stroke color
--product-tour-current-dot-background-color edits product-tour control dot background color when it points to a current image
--product-tour-dot-background-color edits product-tour control dot background color
--product-tour-mobile-close-button-outline-color edits product-tour mobile close button outline color
--product-tour-mobile-close-button-stroke-color edits product-tour mobile close button stroke color
CSS Shadow Parts
Part Description
hotspot-button points to the hotspot buttons
hotspot-button-annotation points to the hotspot button annotation
hotspot-button-inner-circle points to the inner circle of the hotspot button
mobile-product-tour-button-default points to the default mobile product tour launch button
product-tour points to the <Product-tour> element
product-tour-carousel-media points to the media housed inside media carousels
product-tour-close-container points to the side panel close button container
product-tour-close-default points to the side panel default close button
product-tour-container points to the side panel container
product-tour-feature-content-container points to the side panel feature content containers
product-tour-feature-description points to the description of the feature text
product-tour-feature-media-container points to the containers housing feature media
product-tour-feature-text-container points to the container housing the feature text
product-tour-feature-title points to the title of the feature text
product-tour-inner-content-container points to the side panel inner content container
product-tour-media-carousel points to the feature media carousels
product-tour-media-carousel-dot points to the control buttons for the media carousels
product-tour-media-controls-container points to the containers housing the control buttons for the media carousels
product-tour-media-title points to the feature media titles
Slots
Name Description
mobile-product-tour-button replaces the mobile product tour launch button
Theming

It is possible to create a theme by combining CSS Shadow Parts and CSS Custom Properties.

Naming Conventions

For consistency’s sake, please name your client custom properties like this

--{client}_{color-name} or --{client}_{property-name}

Selectors

You can target the web component directly using its tag name epigraph-ar

Format

Organization here is optional but is recommended best practice.

You can theme the button by replacing the default HTML

and/or by some specific styling

epigraph-ar {
  /* define client colors and properties first here
        keep in mind that the following names
        and values are arbitrary */
  --client_theme-color: #5d5fef;
  --client_color-dark: #1f1f1f;
  --client_color-default: #404040;
  --client_color-light: #ffffff;
  --client_loading-radius: 3rem;
  --client_loading-thickness: 0.625rem;
  /* ... more specific colors if you want */

  /* hotspot theming */
  --hotspot-button-background-color: var(
    defined property for the desired color
  );
  --hotspot-button-border-color: var(
    defined property for the desired color
  );
  --hotspot-button-focus-border-color: var(
    defined property for the desired color
  );
  --hotspot-inner-circle-border-color: var(
    defined property for the desired color
  );
  --hotspot-inner-circle-viewed-border-color: var(
    defined property for the desired color
  );

  /* product tour theming */

  /* mobile */
  --mobile-product-tour-button-background-color: var(
    defined property for the desired color
  );
  --mobile-product-tour-button-text-color: var(
    defined property for the desired color
  );
  --product-tour-mobile-close-button-outline-color: var(
    defined property for the desired color
  );
  --product-tour-mobile-close-button-stroke-color: var(
    defined property for the desired color
  );

  /* general */
  --product-tour-background-color: var(
    defined property for the desired color
  );
  --product-tour-close-button-fill-color: var(
    defined property for the desired color
  );
  --product-tour-close-button-hover-fill-color: var(
    defined property for the desired color
  );
  --product-tour-close-button-hover-stroke-color: var(
    defined property for the desired color
  );
  --product-tour-close-button-stroke-color: var(
    defined property for the desired color
  );
  --product-tour-current-dot-background-color: var(
    defined property for the desired color
  );
  --product-tour-dot-background-color: var(
    defined property for the desired color
  );
}

epigraph-ar::part(hotspot-button) {
  /* desired styles here */
}
epigraph-ar::part(hotspot-button-annotation) {
  /* desired styles here */
}
epigraph-ar::part(hotspot-button-inner-circle) {
  /* desired styles here */
}
epigraph-ar::part(mobile-product-tour-button-default) {
  /* desired styles here */
}
epigraph-ar::part(product-tour) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-carousel-media) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-close-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-close-default) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-feature-content-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-feature-description) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-feature-media-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-feature-text-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-feature-title) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-inner-content-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-media-carousel) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-media-carousel-dot) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-media-controls-container) {
  /* desired styles here */
}
epigraph-ar::part(product-tour-media-title) {
  /* desired styles here */
}

Analytics API

API available for you to modify analytics behavior with GA.

Attributes and Properties
Property Attribute Modifiers Type Default Description
gaEventLabelType ga-event-label-type   string “name” flag to use different values for GA event label

name - use product name or hotspot feature name

sku - use product sku

name and sku - use ‘{name} - {sku}’

sku and name - use ‘{sku} - {name}’
uaCode ua-code   string ”” to be used with client ua-code

Debugging API

API available for you to use for debugging purposes.

Attributes and Properties
Property Attribute Modifiers Type Default Description
name     string “EPIGRAPH-AR” name to be used for the internal logging service
verboseLogging verbose-logging   boolean false used to log debugging information
Events
Event Type Description
epigraph-experience-type
CustomEvent<ExperienceDetails>

ExperienceDetails = {
type: string,
features: string[]
}
custom event to detail what experience is currently being rendered
epigraph-invalid-product   custom event to indicate product associated with the sku is invalid
epigraph-valid-product   custom event to indicate product associated with the sku is valid
epigraph-ar-poster-dismissed   custom event to indicate when the model-viewer poster is dismissed
epigraph-ar-fullscreen-opened   custom event to indicate when fullscreen is opened on the model-viewer
epigraph-ar-fullscreen-close   custom event to indicate when fullscreen is closed on the model-viewer
epigraph-modal-opened   custom event to indicate when the ios fullscreen modal is opened
epigraph-modal-close   custom event to indicate when the ios fullscreen modal is closed

Fully Styled Custom Example

This is a fully custom theme made using the Visual API.

Example HTML Snippet
<epigraph-ar
  CLASS="epigraph-ar custom-theme-showcase"
  viewer-visible
  product-tour-visible
  auto-start
  sku="some-valid-sku"
  ua-code="some-valid-ua-code"
></epigraph-ar>
Example CSS Snippet
:root {
  --custom-cube_top-vector-color: rgba(93, 94, 254, 0.25);
  --custom-cube_left-vector-color: rgba(93, 94, 254, 0.5);
  --custom-cube_right-vector-color: rgba(93, 94, 254, 0.75);
  --custom-cube_frame-color: rgba(93, 94, 254, 1);
}

* {
  box-sizing: border-box;
  outline: none;
  margin: 0;
  padding: 0;
}

html,
body {
  width: 100%;
  height: 100%;
  background-color: #fff;
}

body {
  display: grid;
  place-items: center;
}

.epigraph-ar.custom-theme-showcase {
  --progress-ring-color: var(--epigraph-color_iris);
  --ar-button-border-color: inherit;
  --ar-button-text-color: transparent;

  /* ar icon theming */
  --ar-icon-frame-color: var(--custom-cube_frame-color);
  --ar-icon-hover-frame-color: #ffffff;
  --ar-icon-hover-vector-1-color: #ffffff;
  --ar-icon-hover-vector-2-color: #eeeeee;
  --ar-icon-hover-vector-3-color: #ced6e3;
  --ar-icon-vector-1-color: var(--custom-cube_top-vector-color);
  --ar-icon-vector-2-color: var(--custom-cube_left-vector-color);
  --ar-icon-vector-3-color: var(--custom-cube_right-vector-color);
  --qr-modal-done-button-border-color: inherit;
  --qr-modal-close-button-stroke-color: var(--epigraph-color_iris);
  --qr-modal-instruction-color: var(--epigraph-color_dark-slate-grey);
  --qr-modal-title-color: var(--epigraph-color_night-rider);
  --hotspot-button-border-color: var(--epigraph-color_iris);
  --hotspot-inner-circle-border-color: var(--epigraph-color_iris);
  --mobile-product-tour-button-background-color: var(
    --epigraph-color_iris
  );
  --product-tour-close-button-fill-color: var(
    --epigraph-color_dark-slate-grey
  );
  --product-tour-close-button-hover-fill-color: var(--epigraph-color_iris);
  --product-tour-close-button-hover-stroke-color: var(
    --epigraph-color_white
  );
  --product-tour-close-button-stroke-color: var(--epigraph-color_white);
}

.epigraph-ar.custom-theme-showcase::part(default-ar-button):hover,
.epigraph-ar.custom-theme-showcase::part(qr-modal-done-default):hover {
  color: var(--epigraph-color_white);
  background: var(--epigraph-color_gradient);
  --custom-cube_top-vector-color: #ffffff;
  --custom-cube_left-vector-color: #eeeeee;
  --custom-cube_right-vector-color: #ced6e3;
  --custom-cube_frame-color: #ffffff;
}

.epigraph-ar.custom-theme-showcase::part(default-ar-button)::before,
.epigraph-ar.custom-theme-showcase::part(qr-modal-done-default)::before {
  content: "";
  display: flex;
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 0;
  border-radius: inherit;
  padding: 2px;
  background: var(--epigraph-color_gradient);
  mask: var(--epigraph-color_gradient) content-box, var(
      --epigraph-color_gradient
    );
  -webkit-mask: var(--epigraph-color_gradient) content-box, var(
      --epigraph-color_gradient
    );
  -webkit-mask-composite: xor;
  mask-composite: exclude;
}

.epigraph-ar.custom-theme-showcase::part(qr-modal-background) {
  backdrop-filter: blur(10px) sepia(50%);
}

.epigraph-ar.custom-theme-showcase::part(default-ar-button),
.epigraph-ar.custom-theme-showcase::part(qr-modal-done-default),
.epigraph-ar.custom-theme-showcase::part(qr-modal-requirement-default) {
  color: transparent;
  background: var(--epigraph-color_gradient);
  backdrop-filter: brightness(500%);
  background-clip: text;
  -webkit-background-clip: text;
}

related example

Slider Usage Example

This is an example of using the web component inside a slideshow.

Structure

The html used in this example will follow the tree structure outlined below:

top level container/slider
|
⤷ slides container
| |
| ⤷ slide
| |
| ⤷ slide notifications container
| | |
| | ⤷ product valid notification
| | |
| | ⤷ product invalid notification
| |
| ⤷ <epigraph-ar>
| |
| ⤷ custom poster/3D icon
|
| ...
|
⤷ thumbnails container
|
⤷ thumbnail links
|
⤷ thumbnail images

        ...
Templates

Replacement Poster

This example makes use of the poster slot of our web component. You can structure these images however you need, in our case, we did icon layer on top of a background layer

<section class="replacement-poster" slot="poster">
  <img src="/path/to/image" alt="Icon Text" />
  <img src="/path/to/image" alt="Background Text" />
</section>

Slide

In this template, we want to add class names to help us target each notification span so that we can style them accordingly. Please replace the ${sku} with a valid product sku and ${posterTemplate} with the replacement poster template mentioned above.

<section class="notifications">
  <article class="product-validated">
    <img src="/path/to/success/icon" alt="done icon" />
    Product has been validated!
  </article>
  <article class="product-invalidated">
    <img src="/path/to/error/icon" alt="error icon" />
    Product is not valid!
  </article>
</section>
<epigraph-ar
  class="epigraph-ar use-viewer-maximizable custom-theme-showcase"
  viewer-visible
  viewer-maximizable
  sku="${sku}"
  ua-code="UA-189030533-2"
  auto-start
  >${posterTemplate}</epigraph-ar
>

Main Container

We put all of the other templates into this one, keep in mind that we need to replace all the ${slideTemplate} with the slide template mentioned above. Furthermore, the image sources used in this example are from a public image placeholder API, and we utilized the standard hyperlinking behavior to jump to individual slides (this is the same way that popular doc websites implement sections that you can jump to from a link).

<section class="slides">
  <article class="slide" id="slide-1">${slideTemplate}</article>
  <article class="slide" id="slide-2">${slideTemplate}</article>
  <article class="slide" id="slide-3">${slideTemplate}</article>
</section>
<section class="thumbs">
  <a href="#slide-1"><img src="https://picsum.photos/150" /></a>
  <a href="#slide-2"><img src="https://picsum.photos/150" /></a>
  <a href="#slide-3"><img src="https://picsum.photos/150" /></a>
</section>
Script

For this example, we used the following script in order to manipulate the web component and achieve the custom behavior we want.

// after the final html composite has been inserted, we want to select each
// viewer in order to perform DOM manipulation
document.querySelectorAll("epigraph-ar").forEach((viewer) => {
  // in the following two methods, we add the showing-success class name
  // to the notifications section in order to apply the keyframe animation
  // defined in our CSS, and remove it a short duration later
  const showSuccessNotification = (e) => {
    e.target.parentElement.children[0].classList.add("showing-success");
    setTimeout(
      () =>
        e.target.parentElement.children[0].classList.remove(
          "showing-success"
        ),
      5000
    );
  };
  const showErrorNotification = (e) => {
    e.target.parentElement.children[0].classList.add("showing-error");
    setTimeout(
      () =>
        e.target.parentElement.children[0].classList.remove(
          "showing-error"
        ),
      5000
    );
  };

  // In this method, we repeatedly try to check if the internal model-viewer
  // element has been rendered, if not, we keep trying every 1 second.
  // Otherwise, we remove the timeout and attach a listener to listen
  // to internal model-visibility events, which are fired each time model
  // visibility changes
  const showArButton = (e) => {
    const modelViewer = e.target.shadowRoot.querySelector("model-viewer");
    if (!modelViewer) {
      console.warn("model-viewer has not rendered yet, trying again ...");
      setTimeout(() => showArButton(e), 1000);
      return;
    }
    clearTimeout(() => showArButton(e), 1000);
    modelViewer.addEventListener("model-visibility", (e) =>
      e.detail.visible
        ? viewer.classList.add("showing-ar-button")
        : viewer.classList.remove("showing-ar-button")
    );
  };

  // here we listen to all of the available epigraph events and handle
  // each case accordingly
  viewer.addEventListener(
    "epigraph-valid-product",
    showSuccessNotification
  );
  viewer.addEventListener(
    "epigraph-invalid-product",
    showErrorNotification
  );
  viewer.addEventListener("epigraph-experience-type", showArButton);
});

related example

<epigraph-spinner>

Latest Release

Epigraph’s custom web component for spinners

Quick Start

You need to import our web component module. We recommend that you do this in the head. It’s important that type="module" is specified.

<head>
  <script
    type="module"
    async
    src="https://www.unpkg.com/@epigraph/spinner/dist/epigraph-spinner.min.js"
  ></script>
</head>

You can insert epigraph-spinner elements anywhere you’d like. Epigraph Spinner currently serves one purpose: to embed a spinner directly in your page.

<epigraph-spinner sku="abc123" ua-code="valid-ua-code"></epigraph-spinner>

Attributes

Expand Section
Name Type Default Value Description
sku String, required "null" Insert your product code/item no. for specifying which spinner to load (from our DB). This is a reactive attribute, so changing the sku attribute will force a spinner reload.
ua-code String, required "" Insert your ua-code for google analytics in order to send analytics event to your dashboard.
ga-event-label-type String "name" Specify which type of GA event label you would like to use. Options are: “name” - for product name, “sku” - for product sku, “name and sku” a combinator string that results in “{name} - {sku}”
ga-spinner-availability-event Boolean true toggle whether to send a spinner available GA event

Events (with example usage)

Expand Section

"epigraph-valid-product"

You can register to this event from <epigraph-spinner> to know when <epigraph-spinner> has successfully fetched a valid product. You can leverage this event to enable custom actions that should only happen for products with epigraph spinners.

// target <epigraph-spinner>
const eSpin = document.querySelector("epigraph-spinner");

// add the event listener
eSpin.addEventListener("epigraph-valid-product", () => {
  // do something
});

"epigraph-invalid-product"

You can register to this event from <epigraph-spinner> to know if <epigraph-spinner> has failed to fetch a valid product.

// target <epigraph-spinner>
const eSpin = document.querySelector("epigraph-spinner");

// add the event listener
eSpin.addEventListener("epigraph-invalid-product", () => {
  // do something
});

Methods

Expand Section
Name Description
load() Call this method to set spinner loading to start immediately